Doc/library/os.rst: `os.waitid` absent on MacOS #104558

johnhawkinson · 2023-05-16T18:07:38Z

os.waitid() is disabled on MacOS, and that's not documented.
It's not precisely clear why its disabled, and it was discussed in #55021 (deeplink) which was closed without resolution.

But regardless of why, the documentation needs to clearly reflect that the function is not available.

I've followed the model of os.fdatasync() and noted the lack of availability in the Note section, rather than the Availability section. Absent that precedent, I would have instead changed Availability to Unix, not Emscripten, not Macos, not WASI, perhaps somewhat consistent with CLOCK_UPTIME_RAW in time.rst L866.

I hope this is appropriate for a PR without an Issue, but if I'm wrong, I apologize and am happy to file an Issue.

📚 Documentation preview 📚: https://cpython-previews--104558.org.readthedocs.build/

cpython-cla-bot · 2023-05-16T18:08:05Z

All commit authors signed the Contributor License Agreement.

johnhawkinson · 2023-05-17T18:48:18Z

os.waitid() is disabled on MacOS, and that's not documented.

I probably should have supported the statement that it's disabled, sorry.
As discussed in the linked issue, the disabling is from the && !defined(__APPLE__) here:

cpython/Modules/posixmodule.c

Lines 9191 to 9213 in c649df6

    
           #if defined(HAVE_WAITID) && !defined(__APPLE__) 
        
           /*[clinic input] 
        
           os.waitid 
        
               idtype: idtype_t 
        
                   Must be one of be P_PID, P_PGID or P_ALL. 
        
               id: id_t 
        
                   The id to wait on. 
        
               options: int 
        
                   Constructed from the ORing of one or more of WEXITED, WSTOPPED 
        
                   or WCONTINUED and additionally may be ORed with WNOHANG or WNOWAIT. 
        
               / 
        
           Returns the result of waiting for a process or processes. 
        
           Returns either waitid_result or None if WNOHANG is specified and there are 
        
           no children in a waitable state. 
        
           [clinic start generated code]*/ 
        
           static PyObject * 
        
           os_waitid_impl(PyObject *module, idtype_t idtype, id_t id, int options) 
        
           /*[clinic end generated code: output=5d2e1c0bde61f4d8 input=d8e7f76e052b7920]*/ 
        
           {

Doc/library/os.rst

ronaldoussoren · 2023-12-27T22:47:06Z

The more interesting question here is why os.waitid is not exposed on macOS.

There's some discussion in #55021, waitid was not exposed for unclear reasons. IMHO we should expose it for macOS and if needed document limitations with the API (it was disabled for unspecified problems in versions of the OS that we no longer supported in our installers).

johnhawkinson · 2023-12-27T22:52:45Z

The more interesting question here is why os.waitid is not exposed on macOS.

You know…no it's not!

If it takes 6 months to get a doc fix in and 12 months to have a policy debate and maybe change the policy and get a code fix in, I am entirely uninterested in postponing the former in favor of the latter. Open a new PR or Issue to expose waitid but don't hold up fixing the broken documentation now.

Thank you. I am not as bitter as I sound.

ronaldoussoren · 2023-12-28T09:01:38Z

Thank you. I am not as bitter as I sound.

I don't know about other core devs, but personally I only regularly check GitHub issues for things to work on. That's mostly out of habit, but we do have a longstanding culture of having issues for almost all changes. I'm not going to argue that's a good thing, but it does explain why PRs without an issue can get lost and not get core dev attention.

Anyway, I'll file an issue about exposing os.waitid in 3.13 and will return to this PR soon with the intention to merge it.

Co-authored-by: AN Long <[email protected]>

ronaldoussoren

LGTM

Thanks for the PR!

Doc/library/os.rst

miss-islington-app · 2023-12-28T19:36:23Z

Thanks @johnhawkinson for the PR, and @ronaldoussoren for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11, 3.12.
🐍🍒⛏🤖

* Doc/library/os.rst: `os.waitid` absent on MacOS (cherry picked from commit db1c882) Co-authored-by: John Hawkinson <[email protected]> Co-authored-by: AN Long <[email protected]>

bedevere-app · 2023-12-28T19:36:31Z

GH-113553 is a backport of this pull request to the 3.12 branch.

* Doc/library/os.rst: `os.waitid` absent on MacOS (cherry picked from commit db1c882) Co-authored-by: John Hawkinson <[email protected]> Co-authored-by: AN Long <[email protected]>

bedevere-app · 2023-12-28T19:36:36Z

GH-113554 is a backport of this pull request to the 3.11 branch.

…113553) Doc/library/os.rst: `os.waitid` absent on MacOS (GH-104558) * Doc/library/os.rst: `os.waitid` absent on MacOS (cherry picked from commit db1c882) Co-authored-by: John Hawkinson <[email protected]> Co-authored-by: AN Long <[email protected]>

…113554) Doc/library/os.rst: `os.waitid` absent on MacOS (GH-104558) * Doc/library/os.rst: `os.waitid` absent on MacOS (cherry picked from commit db1c882) Co-authored-by: John Hawkinson <[email protected]> Co-authored-by: AN Long <[email protected]>

* Doc/library/os.rst: `os.waitid` absent on MacOS Co-authored-by: AN Long <[email protected]>

bedevere-bot added awaiting review docs Documentation in the Doc dir skip news labels May 16, 2023

Doc/library/os.rst: os.waitid absent on MacOS

e7bc73d

johnhawkinson force-pushed the 2024.05.16.osx-waitid-doc branch from b2399e2 to e7bc73d Compare May 16, 2023 18:11

arhadthedev added OS-mac skip issue labels May 16, 2023

aisk reviewed Sep 17, 2023

View reviewed changes

Doc/library/os.rst Outdated Show resolved Hide resolved

ronaldoussoren added needs backport to 3.11 only security fixes needs backport to 3.12 bug and security fixes labels Dec 28, 2023

Update Doc/library/os.rst

273d105

Co-authored-by: AN Long <[email protected]>

ronaldoussoren approved these changes Dec 28, 2023

View reviewed changes

Doc/library/os.rst Outdated Show resolved Hide resolved

bedevere-app bot added awaiting merge and removed awaiting review labels Dec 28, 2023

Merge branch 'main' into 2024.05.16.osx-waitid-doc

a80edf3

ronaldoussoren merged commit db1c882 into python:main Dec 28, 2023
18 checks passed

bedevere-app bot removed the awaiting merge label Dec 28, 2023

bedevere-app bot removed the needs backport to 3.12 bug and security fixes label Dec 28, 2023

bedevere-app bot removed the needs backport to 3.11 only security fixes label Dec 28, 2023

kulikjak pushed a commit to kulikjak/cpython that referenced this pull request Jan 22, 2024

Doc/library/os.rst: os.waitid absent on MacOS (python#104558)

4f91191

* Doc/library/os.rst: `os.waitid` absent on MacOS Co-authored-by: AN Long <[email protected]>

aisk added a commit to aisk/cpython that referenced this pull request Feb 11, 2024

Doc/library/os.rst: os.waitid absent on MacOS (python#104558)

33937bc

* Doc/library/os.rst: `os.waitid` absent on MacOS Co-authored-by: AN Long <[email protected]>

Glyphack pushed a commit to Glyphack/cpython that referenced this pull request Sep 2, 2024

Doc/library/os.rst: os.waitid absent on MacOS (python#104558)

d5ffe7b

* Doc/library/os.rst: `os.waitid` absent on MacOS Co-authored-by: AN Long <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doc/library/os.rst: `os.waitid` absent on MacOS #104558

Doc/library/os.rst: `os.waitid` absent on MacOS #104558

johnhawkinson commented May 16, 2023 •

edited by github-actions bot

Loading

cpython-cla-bot bot commented May 16, 2023 •

edited

Loading

johnhawkinson commented May 17, 2023

ronaldoussoren commented Dec 27, 2023

johnhawkinson commented Dec 27, 2023

ronaldoussoren commented Dec 28, 2023

ronaldoussoren left a comment

miss-islington-app bot commented Dec 28, 2023

bedevere-app bot commented Dec 28, 2023

bedevere-app bot commented Dec 28, 2023

Doc/library/os.rst: os.waitid absent on MacOS #104558

Doc/library/os.rst: os.waitid absent on MacOS #104558

Conversation

johnhawkinson commented May 16, 2023 • edited by github-actions bot Loading

cpython-cla-bot bot commented May 16, 2023 • edited Loading

johnhawkinson commented May 17, 2023

ronaldoussoren commented Dec 27, 2023

johnhawkinson commented Dec 27, 2023

ronaldoussoren commented Dec 28, 2023

ronaldoussoren left a comment

Choose a reason for hiding this comment

miss-islington-app bot commented Dec 28, 2023

bedevere-app bot commented Dec 28, 2023

bedevere-app bot commented Dec 28, 2023

Doc/library/os.rst: `os.waitid` absent on MacOS #104558

Doc/library/os.rst: `os.waitid` absent on MacOS #104558

johnhawkinson commented May 16, 2023 •

edited by github-actions bot

Loading

cpython-cla-bot bot commented May 16, 2023 •

edited

Loading